/* vim: set expandtab tabstop=4 softtabstop=4 shiftwidth=4: */
/* Copyright (C) 2012 Zongyou Yao. All rights reserved.     */

#ifndef ARRAY_INCLUDED
#define ARRAY_INCLUDED

/**
 * Array indices run from zero to N - 1, where N is the length of the array.
 * The empty array has no elements. It is a checked runtime error to pass a null T
 * to any Array function.
 */
typedef struct array_t * array_t;

/**
 * Allocates, initializes, and returns a new array of length elements each
 * of size bytes. The elements are cleared. It is a checked runtime error
 * for length < 0 or size <= 0.
 * Exception mem_failed can be raised.
 */
array_t array_new(int length, int size);

/**
 * Deallocates and clears *array. It is a checked runtime error for array or *array
 * to be null.
 */
void array_free(array_t *array);

/**
 * Returns the number of elements in array.
 */
int array_length(array_t array);

/**
 * Returns the size in bytes of the elements in array.
 */
int array_size(array_t array);

/**
 * Returns a pointer to the ith element in array. It is a checked runtime error
 * for i < 0 or i >= N, where N is the length of array.
 */
void * array_get(array_t array, int i);

/**
 * Copies array_size(array) bytes from elem into the ith element in
 * array and returns elem. It is a checked runtime error for elem = null
 * or for i < 0 or i >= N, where N is the length of array.
 */
void * array_put(array_t array, int i, void *elem);

/**
 * changes the number of elements in array to length. If length
 * exceeds the original length, the excess elements are cleared.
 * It is a checked runtime error for length < 0.
 * Exception mem_failed can be raised.
 */
void array_resize(array_t array, int length);

/**
 * Creates and returns a new array that holds the initial length elements
 * from array. If length exceeds the length of array, the excess elements
 * are cleared.
 * Exception mem_failed can be raised.
 */
array_t array_copy(array_t array, int length);

#endif
